<!-- ##### SECTION Long_Description ##### -->
<para>
+GtkBinding provide a mechanism for configuring Gtk+ key bindings through RC files.
+This eases key binding adjustments for application developers as well as users and
+provides Gtk+ users or administrators with high key binding configurability which
+require no application or toolkit side changes.
+</para>
+
+<refsect2>
+<anchor id="gtk-bindings-install"/>
+<title>Installing a key binding</title>
+
+<para>
+A resource file binding consists of a 'binding' definition and a match statement to
+apply the binding to specific widget types. Details on the matching mechanism are
+described under <link linkend="gtkrc-pathnames-and-patterns">Pathnames and patterns</link>.
+Inside the binding definition, key combinations are bound to specific signal emissions
+on the target widget. Key combinations are strings consisting of an optional #GdkModifierType
+name and <link linkend="gdk-Keyboard-Handling">key names</link> such as those defined in
+<filename><gdk/gdkkeysyms.h></filename> or returned from gdk_keyval_name(), they have
+to be parsable by gtk_accelerator_parse().
+Specifications of signal emissions consist of a string identifying the signal name, and
+a list of signal specific arguments in parenthesis.
+
+For example for binding Control and the left or right cursor keys of a #GtkEntry widget to the
+#GtkEntry::move-cursor signal, so movement occurs in 3 letter steps,
+the following binding can be used:
+
+<informalexample><programlisting>
+binding "MoveCursor3" {
+ bind "<Control>Right" {
+ "move-cursor" (visual-positions, 3, 0)
+ }
+ bind "<Control>Left" {
+ "move-cursor" (visual-positions, -3, 0)
+ }
+}
+class "GtkEntry" binding "MoveCursor3"
+</programlisting></informalexample>
+</para>
+
+
+<anchor id="gtk-bindings-unbind"/>
+<title>Unbinding existing key bindings</title>
+<para>
+Gtk+ already defines a number of useful bindings for the widgets it provides.
+Because custom bindings set up in RC files take precedence over the default bindings
+shipped with Gtk+, overriding existing bindings as demonstrated in
+<link linkend="gtk-bindings-install">Installing a key binding</link>
+works as expected. The same mechanism can not be used to "unbind" existing bindings,
+however.
+
+<informalexample><programlisting>
+binding "MoveCursor3" {
+ bind "<Control>Right" { }
+ bind "<Control>Left" { }
+}
+class "GtkEntry" binding "MoveCursor3"
+</programlisting></informalexample>
+
+The above example will not have the desired effect of causing "<Control>Right"
+and "<Control>Left" key presses to be ignored by Gtk+. Instead, it just causes
+any existing bindings from the bindings set "MoveCursor3" to be deleted, so when
+"<Control>Right" or "<Control>Left" are pressed, no binding for these keys
+is found in binding set "MoveCursor3". Gtk+ will thusly continue to search for matching
+key bindings, and will eventually lookup and find the default Gtk+ bindings for entries
+which implement word movement. To keep Gtk+ from activating its default bindings, the
+"unbind" keyword can be used like this:
+
+<informalexample><programlisting>
+binding "MoveCursor3" {
+ unbind "<Control>Right"
+ unbind "<Control>Left"
+}
+class "GtkEntry" binding "MoveCursor3"
+</programlisting></informalexample>
+
+Now, Gtk+ will find a match when looking up "<Control>Right" and "<Control>Left"
+key presses before it resorts to its default bindings, and the match instructs it to abort
+("unbind") the search, so the key presses are not consumed by this widget.
+As usual, further processing of the key presses, e.g. by an entries parent widget,
+is now possible.
</para>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
+
+<varlistentry>
+<term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>
+</term>
+<listitem><para>installing and using keyboard short-cuts.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><link linkend="Resource-Files">Resource Files</link>
+</term>
+<listitem><para>Gtk+ Resource Files - behavior and style definitions.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GtkBindingSet ##### -->
<para>
-
+A binding set maintains a list of activatable key bindings.
+A single binding set can match multiple types of widgets.
+Similar to styles, widgets can be mapped by widget name paths, widget class paths or widget class types.
+When a binding within a set is matched upon activation, an action signal is emitted on
+the target widget to carry out the actual activation.
</para>
-@set_name:
-@priority:
-@widget_path_pspecs:
-@widget_class_pspecs:
-@class_branch_pspecs:
-@entries:
-@current:
-@parsed:
+@set_name: unique binding set name
+@priority: unused
+@widget_path_pspecs: widgets matched by path that this binding set applies to
+@widget_class_pspecs: widgets matched by class path that this binding set applies to
+@class_branch_pspecs: widgets matched by class that this binding set applies to
+@entries: the key binding entries in this binding set
+@current: implementation detail
+@parsed: whether this binding set stems from an RC file and is reset upon theme changes
<!-- ##### STRUCT GtkBindingEntry ##### -->
<para>
-
+Each key binding element of a binding sets binding list is represented by a #GtkBindingEntry.
</para>
-@keyval:
-@modifiers:
-@binding_set:
-@destroyed:
-@in_emission:
-@set_next:
-@hash_next:
-@signals:
+@keyval: key value to match
+@modifiers: key modifier to match
+@binding_set: binding set this entry belongs to
+@destroyed: implementation detail
+@in_emission: implementation detail
+@set_next: linked list of entries maintained by binding set
+@hash_next: implementation detail
+@signals: action signals of this entry
<!-- ##### STRUCT GtkBindingSignal ##### -->
<para>
-
+A #GtkBindingSignal stores the necessary information to activate a widget
+in response to a key press via a signal emission.
</para>
-@next:
-@signal_name:
-@n_args:
-@args:
+@next: implementation detail
+@signal_name: the action signal to be emitted
+@n_args: number of arguments specified for the signal
+@args: the arguments specified for the signal
<!-- ##### STRUCT GtkBindingArg ##### -->
<para>
-
+A #GtkBindingArg holds the data associated with an argument for a
+key binding signal emission as stored in #GtkBindingSignal.
</para>
-@arg_type:
+@arg_type: implementation detail
<!-- ##### FUNCTION gtk_binding_set_new ##### -->
<para>
-
+Gtk+ maintains a global list of binding sets. Each binding set has a unique name
+which needs to be specified upon creation.
</para>
-@set_name:
-@Returns:
+@set_name: unique name of this binding set
+@Returns: new binding set
<!-- ##### FUNCTION gtk_binding_set_by_class ##### -->
<para>
-
+This function returns the binding set named after the type name of the passed
+in class structure. New binding sets are created on demand by this function.
</para>
-@object_class:
-@Returns:
+@object_class: a valid #GtkObject class
+@Returns: the binding set corresponding to @object_class
<!-- ##### FUNCTION gtk_binding_set_find ##### -->
<para>
-
+Find a binding set by its globally unique name.
+The @set_name can either be a name used for gtk_binding_set_new() or the
+type name of a class used in gtk_binding_set_by_class().
</para>
-@set_name:
-@Returns:
+@set_name: unique binding set name
+@Returns: %NULL or the specified binding set
<!-- ##### FUNCTION gtk_bindings_activate ##### -->
<para>
-
+Find a key binding matching @keyval and @modifiers and activate the binding
+on @object.
</para>
-@object:
-@keyval:
-@modifiers:
-@Returns:
+@object: object to activate when binding found
+@keyval: key value of the binding
+@modifiers: key modifier of the binding
+@Returns: %TRUE if a binding was found and activated
<!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
<para>
-
+<!-- documented inline -->
</para>
@object:
<!-- ##### FUNCTION gtk_binding_set_activate ##### -->
<para>
-
+Find a key binding matching @keyval and @modifiers within @binding_set
+ and activate the binding on @object.
</para>
-@binding_set:
-@keyval:
-@modifiers:
-@object:
-@Returns:
+@binding_set: the binding set to constrain the search to
+@keyval: key value of the binding
+@modifiers: key modifier of the binding
+@object: object to activate when binding found
+@Returns: %TRUE if a binding was found and activated
<!-- ##### MACRO gtk_binding_entry_add ##### -->
<para>
-
+Deprecated.
</para>
<!-- ##### FUNCTION gtk_binding_entry_clear ##### -->
<para>
-
+Deprecated as public API, used only internally.
</para>
@binding_set:
<!-- ##### FUNCTION gtk_binding_entry_add_signal ##### -->
<para>
-
+Override or install new key binding for @keyval with @modifiers on @binding_set.
+When the binding is activated, @signal_name will be emitted on the target widget,
+with @n_args @Varargs used as arguments.
</para>
-@binding_set:
-@keyval:
-@modifiers:
-@signal_name:
-@n_args:
-@Varargs:
+@binding_set: @binding_set to install an entry for
+@keyval: key value of binding to install
+@modifiers: key modifier of binding to install
+@signal_name: signal to execute upon activation
+@n_args: number of arguments to @signal_name
+@Varargs: arguments to @signal_name
<!-- ##### FUNCTION gtk_binding_set_add_path ##### -->
<para>
-
+This function is used internally by the GtkRC parsing mechanism to assign match
+patterns to #GtkBindingSet structures.
</para>
-@binding_set:
-@path_type:
-@path_pattern:
-@priority:
+@binding_set: binding set to add a path to
+@path_type: path type the pattern applies to
+@path_pattern: the actual match pattern
+@priority: binding priority
<!-- ##### FUNCTION gtk_binding_entry_remove ##### -->
<para>
-
+Remove a binding previously installed via gtk_binding_entry_add_signal() on
+@binding_set.
</para>
-@binding_set:
-@keyval:
-@modifiers:
+@binding_set: @binding_set to remove an entry of
+@keyval: key value of binding to remove
+@modifiers: key modifier of binding to remove
<!-- ##### FUNCTION gtk_binding_entry_add_signall ##### -->
<para>
-
+Deprecated.
</para>
-@binding_set:
-@keyval:
-@modifiers:
-@signal_name:
-@binding_args:
+@binding_set: binding set to add a signal to
+@keyval: key value
+@modifiers: key modifier
+@signal_name: signal name to be bound
+@binding_args: list of #GtkBindingArg signal arguments
<!-- ##### FUNCTION gtk_binding_parse_binding ##### -->
<para>
-
+Deprecated as public API, used only internally.
</para>
-@scanner:
-@Returns:
-
-
+@scanner: GtkRC scanner
+@Returns: expected token upon errors
projects / gtk4.git / commitdiff